package midas.mw.crt.interfaces;

import midas.mw.crt.common.IPMessage;

import java.util.Properties;

/**
 * It defines the API provided by the CRT to other MIDAS components. The CRT will
 * not be directly accessible by the applications.
 * <p> 
 * Middleware components will be able of receiving CRT messages or notifications
 * implementing the <i>CrtCallback</i>. Others (for example subcomponents) have
 * to use the 'addCrtListener' function to be included as possible recipients.  
 *
 */

public interface Crt
{		
	/**
	 * Sends the specified message.
	 * 
	 * @param ipMessage IPMessage storing the necessary information to send
	 *  		the message
	 * @return Message identifier. This value will be unique and will identify 
	 * 			the message in the CRT
	 */
	public long sendMessage(IPMessage ipMessage);
	
	/**
	 * Sends the specified message to all MIDAS nodes. CRT will not wait for answers
	 * for messages sent through this method
	 * 
	 * @param ipMessage IPMessage storing the necessary information to send
	 *  		the message
	 */
	public void sendBroadcastMessage(IPMessage ipMessage);
	
	/**
	 * Sends the specified message to all one-hop MIDAS nodes. CRT will not wait for answers
	 * for messages sent through this method
	 * <p>
	 * If the node has a wireless network interface in ad-hoc mode, it will send
	 * the message to all one-hop MIDAS nodes.
	 * If not, it will send the message to the Central Node
	 * 
	 * @param ipMessage IPMessage storing the necessary information to send
	 *  		the message
	 */
	public void sendOneHopMessage(IPMessage ipMessage);
	
	/**
	 * Delete a message stored in the CRT to be sent.
	 *  
	 * @param messageId Message identifier. This value will be unique and will 
	 * 			identify the message in the CRT
	 */
	public void deleteMessage(long messageId);
	
	/**
	 * Returns the associated MIDAS node identifier.
	 * 
	 * @return The associated MIDAS node identifier
	 */
	public String getOwnNodeId();
	
	/**
	 * Provides the network information about nodes forming the neighbourhood of
	 * the node
	 * <p>
	 * In ad hoc wireless networks it will use the information provided by the OLSR
	 * protocol. In infrastructure-based networks it will provide different 
	 * information depending on the node type and the parameters passed.That is, 
	 * in a MANET network it will return the nodes between the specified hops. In a
	 * infrastructured network depending on the node:
	 * <p>
	 * For a User Node, if the maximum number of hops is 0, it will return all the 
	 * MIDAS nodes. If the maximum number of hops is 1, it will return the Central 
	 * Node which is connected to. If the maximum number of hops is  > 1, it will 
	 * return the rest of Central Nodes or Gateways Nodes
	 * <p>
	 * For a Central Node or Gateway Node, if the maximum number of hops is 0, it 
	 * will return all the MIDAS nodes. If the maximum number of hops is > 0 it 
	 * will return the rest of Central Nodes or Gateways Nodes

	 * 
	 * @param minNumHops Minimum number of hops the requested nodes should be away
	 * @param maxNumHops Maximum number of hops the requested nodes should be away
	 * @return A Properties object associating MIDAS node identifiers to the number
	 * 			of hops from the requesting node. It will be different if the node 
	 * 			has a wireless network interface in ad-hoc mode or not. 			
	 */
	public Properties getNeighbourhoodInfo(int minNumHops, int maxNumHops);
	
	
	/**
	 * This method registers the request of an component to be notified about 
	 * the presence of some node in the network.
	 * 
	 * @param crtUser Name of the component requesting the information
	 * @param nodeId MIDAS node identifier of the node for the presence request
	 */
	public void subscribePresence(String crtUser, String nodeId);
	
	/**
	 * This method cancels the request of an component to be notified about the presence of 
	 * some node in the network.
	 * 
	 * @param crtUser Name of the application/component canceling the request of information
	 * @param nodeId MIDAS node identifier of the node for the presence request. If null the
	 * 			node does not want information about the presence of any node
	 */
	public void unsubscribePresence(String crtUser, String nodeId);
	
	/**
	 * This method adds a CRT Listener (user) for the CRT Component.
	 * 
	 * @param crtUser Name of the CRT listener
	 * @param listener Object associated to this listener
	 */
	public void addCrtListener(String crtUser,CrtCallback listener);

	/**
	 * This method removes a CRT Listener (user) for the CRT Component.
	 * 
	 * @param crtUser Name of the CRT listener
	 */	
	public void removeCrtListener(String crtUser);
	
	/**
	 * Sends data message to the node(s) denoted by a context based destination address.
	 *
	 * @param destination A context based address describing the destination endpoint(s)
	 * 			for this message.
	 * @param payload Any data converted to byte[]
	 * @param flags A parameter for controlling transmission in case of messages
	 *  		composed of multiple packets. Value 0 means a single packet, 1 
	 *  		means that another packet will follow, 2 means that it is the 
	 *  		last packet of the message. Only 0 value is supported in POC v0.5 
	 */
	public void sendMessage(String destination, byte[] payload, int flags);

	
	/**
	 * Register an object which implements callback methods used by the 
	 * CBR component.
	 *
	 * @param cbrCallback The object which implements the crtCallback interface
	 * 			and in particular the callback methods used by CBR 
	 */	
	public void registerCBRCallback(CrtCallback cbrCallback);
}
